{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": [
     "hide"
    ]
   },
   "outputs": [],
   "source": [
    "import seaborn as sns; sns.set_theme(style=\"ticks\")"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "The default plot kind is a histogram:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "penguins = sns.load_dataset(\"penguins\")\n",
    "sns.displot(data=penguins, x=\"flipper_length_mm\")"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "Use the ``kind`` parameter to select a different representation:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.displot(data=penguins, x=\"flipper_length_mm\", kind=\"kde\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There are three main plot kinds; in addition to histograms and kernel density estimates (KDEs), you can also draw empirical cumulative distribution functions (ECDFs):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.displot(data=penguins, x=\"flipper_length_mm\", kind=\"ecdf\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "While in histogram mode, it is also possible to add a KDE curve:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.displot(data=penguins, x=\"flipper_length_mm\", kde=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To draw a bivariate plot, assign both ``x`` and ``y``:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.displot(data=penguins, x=\"flipper_length_mm\", y=\"bill_length_mm\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Currently, bivariate plots are available only for histograms and KDEs:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.displot(data=penguins, x=\"flipper_length_mm\", y=\"bill_length_mm\", kind=\"kde\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For each kind of plot, you can also show individual observations with a marginal \"rug\":"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "g = sns.displot(data=penguins, x=\"flipper_length_mm\", y=\"bill_length_mm\", kind=\"kde\", rug=True)"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "Each kind of plot can be drawn separately for subsets of data using ``hue`` mapping:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.displot(data=penguins, x=\"flipper_length_mm\", hue=\"species\", kind=\"kde\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Additional keyword arguments are passed to the appropriate underlying plotting function, allowing for further customization:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.displot(data=penguins, x=\"flipper_length_mm\", hue=\"species\", multiple=\"stack\")"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "The figure is constructed using a :class:`FacetGrid`, meaning that you can also show subsets on distinct subplots, or \"facets\":"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.displot(data=penguins, x=\"flipper_length_mm\", hue=\"species\", col=\"sex\", kind=\"kde\")"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "Because the figure is drawn with a :class:`FacetGrid`, you control its size and shape with the ``height`` and ``aspect`` parameters:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.displot(\n",
    "    data=penguins, y=\"flipper_length_mm\", hue=\"sex\", col=\"species\",\n",
    "    kind=\"ecdf\", height=4, aspect=.7,\n",
    ")"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "The function returns the :class:`FacetGrid` object with the plot, and you can use the methods on this object to customize it further:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "g = sns.displot(\n",
    "    data=penguins, y=\"flipper_length_mm\", hue=\"sex\", col=\"species\",\n",
    "    kind=\"kde\", height=4, aspect=.7,\n",
    ")\n",
    "g.set_axis_labels(\"Density (a.u.)\", \"Flipper length (mm)\")\n",
    "g.set_titles(\"{col_name} penguins\")"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "seaborn-py38-latest",
   "language": "python",
   "name": "seaborn-py38-latest"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}
